#%RAML 0.8
---
title: core-command
version: "1.1.x"
baseUri: "http://localhost:48082/api"
protocols: [ HTTP ]

documentation:
  - title: Welcome
    content: |
      Welcome to the Core Command Microservice API Documentation.

schemas: 
    - 
        device: '{"type":"object","$schema":"http://json-schema.org/draft-03/schema#","description":"device or sensor supplying data and taking actuation commands","title":"device","properties":{"id":{"type":"string","required":false,"title":"id"},"created":{"type":"integer","required":false,"title":"created"},"modified":{"type":"integer","required":false,"title":"modified"},"origin":{"type":"integer","required":false,"title":"origin"},"name":{"type":"string","required":false,"title":"name"},"description":{"type":"string","required":false,"title":"description"},"lastConnected":{"type":"integer","required":false,"title":"lastConnected"},"lastReported":{"type":"integer","required":false,"title":"lastReported"},"labels":{"type":"array","required":false,"title":"labels","items":{"type":"string","title":"labels"},"uniqueItems":false},"adminState":{"type":"string","required":false,"title":"adminState"},"operatingState":{"type":"string","required":false,"title":"operatingState"},"addressable":{"type":"object","properties":{"id":{"type":"string","required":false,"title":"id"},"created":{"type":"integer","required":false,"title":"created"},"modified":{"type":"integer","required":false,"title":"modified"},"origin":{"type":"integer","required":false,"title":"origin"},"name":{"type":"string","required":false,"title":"name"},"protocol":{"type":"string","required":false,"title":"protocol"},"address":{"type":"string","required":false,"title":"address"},"port":{"type":"integer","required":false,"title":"port"},"path":{"type":"string","required":false,"title":"path"},"publisher":{"type":"string","required":false,"title":"publisher"},"user":{"type":"string","required":false,"title":"user"},"password":{"type":"string","required":false,"title":"password"},"topic":{"type":"string","required":false,"title":"topic"}}}}}'
    - 
        addressable: '{"type":"object","$schema":"http://json-schema.org/draft-03/schema#","title":"addressable","properties":{"id":{"type":"string","required":false,"title":"id"},"created":{"type":"integer","required":false,"title":"created"},"modified":{"type":"integer","required":false,"title":"modified"},"origin":{"type":"integer","required":false,"title":"origin"},"name":{"type":"string","required":false,"title":"name"},"protocol":{"type":"string","required":false,"title":"protocol"},"address":{"type":"string","required":false,"title":"address"},"port":{"type":"integer","required":false,"title":"port"},"path":{"type":"string","required":false,"title":"path"},"publisher":{"type":"string","required":false,"title":"publisher"},"user":{"type":"string","required":false,"title":"user"},"password":{"type":"string","required":false,"title":"password"},"topic":{"type":"string","required":false,"title":"topic"}}}'
    - 
        commandresponse: '{"type":"object","$schema":"http://json-schema.org/draft-03/schema#","title":"commandresponse","properties":{"host":{"type":"string","required":false,"title":"host"},"device":{"type":"object","$ref":"#/schemas/device","required":false,"title":"device"}}}'
/v1/ping:
    displayName: Ping Resource
    description: Example - http://localhost:48082/api/v1/ping
    get: 
        description: Test service providing an indication that the service is available.
        responses: 
            "200": 
                description: pong as a string
            "500": 
                description: for unanticipated or unknown issues encountered.
/v1/config:
    displayName: Config Resource
    description: Example - http://localhost:48082/api/v1/config
    get:
        description: Fetch the current state of the service's configuration.
        responses:
            "200":
                description: The service's configuration as JSON document
/v1/metrics:
    displayName: Metrics Resource
    description: Example - http://localhost:48082/api/v1/metrics
    get:
        description: Fetch the current state of the service's metrics.
        responses:
            "200":
                description: The service's metrics as JSON document
/v1/device/{id}/command/{commandid}:
    displayName: Issue command
    description: Example - http://localhost:48082/api/v1/device/ebe456c9-b761-42bf-9bf8-1ca0a6c7cfc6/command/8829622b-3c6a-47d2-8afc-80171f474056
    uriParameters: 
        id: 
            displayName: id
            type: string
            required: true
            repeat: false
        commandid: 
            displayName: commandid
            type: string
            required: true
            repeat: false
    get: 
        description: Issue the get command referenced by the command id to the device/sensor (also referenced by database generated id) it is associated to via the device service. ServiceException (HTTP 500) for unanticipated or unknown issues encountered. Throws NotFoundException (HTTP 404) if no device exists by the id provided. Throws LockedException (HTTP 423) if the device is locked (admin state).
        responses: 
            "200": 
                description: String as returned by the device/sensor via the device service.
            "400":
                description: if the request is malformed or unparsable
            "404": 
                description: if no device exists by the id provided
            "423": 
                description: if the device is locked (admin state).
            "500": 
                description: for unanticipated or unknown issues encountered.
    put: 
        description: Issue the put command referenced by the command id to the device/sensor (also referenced by database generated id) it is associated to via the device service. ServiceException (HTTP 500) for unanticipated or unknown issues encountered. Throws NotFoundException (HTTP 404) if no device exists by the id provided. Throws LockedException (HTTP 423) if the device is locked (admin state).
        body: 
            application/json: 
                example: '{"temp":72}'
        responses: 
            "200": 
                description: String as returned by the device/sensor via the device service.
            "400":
                description: if the request is malformed or unparsable
            "404": 
                description: if no device exists by the id provided
            "423": 
                description: if the device is locked (admin state)
            "500": 
                description: for unanticipated or unknown issues encountered.
/v1/device/{id}:
    displayName: Device & their commands by id
    description: Example - http://localhost:48082/api/v1/device/ebe456c9-b761-42bf-9bf8-1ca0a6c7cfc6
    uriParameters: 
        id: 
            displayName: id
            type: string
            required: true
            repeat: false
    get: 
        description: Retrieve a device (by database generated id) and its command offerings. Throws ServiceException (HTTP 500) for unanticipated or unknown issues encountered. Throws NotFoundException (HTTP 404) if no device exists by the id provided.
        responses: 
            "200": 
                description: CommandResponse containing the device and its commands
                body: 
                    application/json: 
                        schema: commandresponse
                        example: '{"name":"livingroomthermostat","id":"ebe456c9-b761-42bf-9bf8-1ca0a6c7cfc6","description":"living room HVAC thermostat","labels":["home","hvac","thermostat"],"adminState":"unlocked","opState":"enabled","lastConnected":0,"lastReported":0,"locationObject":"{lat:45.45,long:47.80}","commands":[{"id":"8829622b-3c6a-47d2-8afc-80171f474056","name":"cooling point","get":{"url":"http://localhost:48082/api/v1/device/ebe456c9-b761-42bf-9bf8-1ca0a6c7cfc6/api/v1/command/8829622b-3c6a-47d2-8afc-80171f474056"},"put":{"url":"http://localhost:48082/api/v1/device/ebe456c9-b761-42bf-9bf8-1ca0a6c7cfc6/api/v1/command/8829622b-3c6a-47d2-8afc-80171f474056","parameters":[{"name":"coolingpoint","value":"72"}],"responses":[{"code":"200","description":"ok","expectedValues":["temperature"]}]}}]}'
            "404": 
                description: if no device exists by the id provided.
            "500": 
                description: for unanticipated or unknown issues encountered.
/v1/device/name/{name}:
    displayName: Device & their commands by name 
    description: Example - http://localhost:48082/api/v1/device/name/livingroomthermostat
    uriParameters: 
        name: 
            displayName: name
            type: string
            required: true
            repeat: false
    get: 
        description: Retrieve a device (by name) and its command offerings. Throws ServiceException (HTTP 500) for unanticipated or unknown issues encountered. Throws NotFoundException (HTTP 404) if no device exists by the name provided.
        responses: 
            "200": 
                description: CommandResponse containing the device and its commands
                body: 
                    application/json: 
                        schema: commandresponse
                        example: '{"name":"livingroomthermostat","id":"ebe456c9-b761-42bf-9bf8-1ca0a6c7cfc6","description":"living room HVAC thermostat","labels":["home","hvac","thermostat"],"adminState":"unlocked","opState":"enabled","lastConnected":0,"lastReported":0,"locationObject":"{lat:45.45,long:47.80}","commands":[{"id":"8829622b-3c6a-47d2-8afc-80171f474056","name":"cooling point","get":{"url":"http://localhost:48082/api/v1/device/ebe456c9-b761-42bf-9bf8-1ca0a6c7cfc6/api/v1/command/8829622b-3c6a-47d2-8afc-80171f474056"},"put":{"url":"http://localhost:48082/api/v1/device/ebe456c9-b761-42bf-9bf8-1ca0a6c7cfc6/api/v1/command/12da905b-97d2-4a58-b9ab-84a71980b363","parameters":[{"name":"coolingpoint","value":"72"}],"responses":[{"code":"200","description":"ok","expectedValues":["temperature"]}]}}]}'
            "404": 
                description: if no device exists by the name provided.
            "500": 
                description: for unanticipated or unknown issues encountered.
/v1/device:
    displayName: Devices & their commands
    description: Example - http://localhost:48082/api/v1/device
    get: 
        description: Retrieve a list of (all) devices and their command offerings. Throws ServiceException (HTTP 500) for unanticipated or unknown issues encountered.
        responses: 
            "200": 
                description: List of CommandResponse (containing the devices and their commands)
                body: 
                    application/json: 
                        schema: commandresponse
                        example: '[{"name":"livingroomthermostat","id":"ebe456c9-b761-42bf-9bf8-1ca0a6c7cfc6","description":"living room HVAC thermostat","labels":["home","hvac","thermostat"],"adminState":"unlocked","opState":"enabled","lastConnected":0,"lastReported":0,"locationObject":"{lat:45.45,long:47.80}","commands":[{"id":"8829622b-3c6a-47d2-8afc-80171f474056","name":"cooling point","get":{"url":"http://localhost:48082/api/v1/device/ebe456c9-b761-42bf-9bf8-1ca0a6c7cfc6/api/v1/command/8829622b-3c6a-47d2-8afc-80171f474056"},"put":{"url":"http://localhost:48082/api/v1/device/ebe456c9-b761-42bf-9bf8-1ca0a6c7cfc6/api/v1/command/12da905b-97d2-4a58-b9ab-84a71980b363","parameters":[{"name":"coolingpoint","value":"72"}],"responses":[{"code":"200","description":"ok","expectedValues":["temperature"]}]}}]}]'
            "500": 
                description: for unanticipated or unknown issues encountered.
/v1/device/name/{name}/command/{commandname}:
    displayName: Issue command
    description: Example - http://localhost:48082/api/v1/device/name/RPIMotionDetector/command/Set_Green_Led
    uriParameters:
        name:
            displayName: name
            type: string
            required: true
            repeat: false
        commandname:
            displayName: commandname
            type: string
            required: true
            repeat: false
    get:
        description: Issue the get command referenced by the command name to the device/sensor (also referenced by name). It is associated to via the device service. ServiceException (HTTP 500) for unanticipated or unknown issues encountered. Throws NotFoundException (HTTP 404) if device with given name does not exist or device doesn't have command with the given commandname. Throws LockedException (HTTP 423) if device adminState is locked.
        responses:
            "200":
                description: String as returned by the device/sensor via the device service.
            "400":
                description: if the request is malformed or unparsable
            "404":
                description: if device with given name does not exist or device doesn't have command with the given commandname.
            "423":
                description: if the device is locked (admin state).
            "500":
                description: for unanticipated or unknown issues encountered.
    put:
        description: Issue the put command referenced by the command name to the device/sensor (also referenced by name) it is associated to via the device service. ServiceException (HTTP 500) for unanticipated or unknown issues encountered. Throws NotFoundException (HTTP 404) if device with given name does not exist or device doesn't have command with the given commandname. Throws LockedException (HTTP 423) if device adminState is locked.
        body:
            application/json:
                example: '{"temp":72}'
        responses:
            "200":
                description: String as returned by the device/sensor via the device service.
            "400":
                description: if the request is malformed or unparsable
            "404":
                description: if device with given name does not exist or device doesn't have a command with the given commandname.
            "423":
                description: if the device is locked (admin state)
            "500":
                description: for unanticipated or unknown issues encountered
/version:
    displayName: Edgex API Version
    description: Example - http://localhost:48082/api/version
    get:
        description: Get the API version
        responses:
            "200":
                description: The service's API version as JSON document
                body:
                  application/json:
                    example:  '{"version":"1.1.0"}'
